Basic Protocol 1: Exploratory Data Analysis with pcaExplorer

Institute of Medical Biostatistics, Epidemiology and Informatics (IMBEI), Mainz
anneludt@uni-mainz.de

Institute of Medical Biostatistics, Epidemiology and Informatics (IMBEI), Mainz
rexha@uni-mainz.de

Institute of Medical Biometry and Statistics (IMBI), Faculty of Medicine and Medical Center, University of Freiburg
binder@imbi.uni-freiburg.de

Institute of Medical Biostatistics, Epidemiology and Informatics (IMBEI), Mainz
strauch@uni-mainz.de

Institute of Medical Biostatistics, Epidemiology and Informatics (IMBEI), MainzCenter for Thrombosis and Hemostasis (CTH), Mainz;

marinif@uni-mainz.de

Compiled date: 2021-09-07

Last edited: 2021-09-07

1 Loading required packages

library("DESeq2")
library("topGO")
library("org.Mm.eg.db")
library("pcaExplorer")
library("ideal")
library("GeneTonic")

2 Introductory Paragraph

pcaExplorer is a Bioconductor package [https://doi.org/10.1186/gb-2004-5-10-r80] which can be seen as a general-purpose interactive companion tool for RNA-seq analyses. pcaExplorer is designed to guide the user in exploring the Principal Components (PC) [https://doi.org/10.2307/1270093] of the data under inspection. Besides the Principal Component Analysis (PCA) [https://doi.org/10.2307/1270093], pcaExplorer also provides tools to detect outlier samples, genes that show particular patterns and additionally provides a functional interpretation of the principal components for further quality assessment and hypothesis generation on the input data.

In this protocol we describe how to launch a Shiny application [https://CRAN.R-project.org/package=shiny] of pcaExplorer with the data of the macrophage dataset [https://doi.org/10.1038/s41588-018-0046-7] which is also distributed via Bioconductor [https://doi.org/10.1186/gb-2004-5-10-r80].

3 Necessary Resources

Hardware

a modern desktop computer or laptop with any up-to-date operating system

Software

R 3.3 or higher, Bioconductor 3.3 or higher, (optional?) RStudio, optional browser to open vignettes

Files (maybe we can describe the sample input here and how to download from Github, I’ve seen that in some papers rather than describing the general input format)

pcaExplorer mainly requires 3 input files in text format. The files are expected to be tab-separated, but also comma- or semicolon-separated files are accepted (see Alternative protocol 1). The first input file is the count matrix which stores the number of times (i.e counts) a certain feature (e.g gene) is found in each sample. In the count matrix, the samples are stored in the columns, while the rows store the individual features (see Fig. 1).

Figure 1 Example of a count matrix - The figure shows the example of a count matrix, with the individual features (here genes) in the rows and the individual samples in the columns. The matrix represents how many times each feature was found in each sample. The shown count matrix is comma-separated, but also semicolon- and tab-separated inputs are accepted (see Alternative protocol 1)

The second input of pcaExplorer is the metadata file. This file stores for each sample the necessary experimental variables. The individual samples represent the rows of the file while the columns save the different experimental variables (see Fig. 2).

Lastly, the third input of pcaExplorer is optional, but highly recommended for an ease of interpretation of the results. The last input is the annotation file. The file contains the feature ids of the count matrix in the rows and at least one column called gene name which contains a more human readable form of the feature ids (e.g. HGNC gene names [https://doi.org/10.1093/nar/gkaa980] if the features are gene ids). Fig. 3 shows an example of an annotation file.

Figure 3 Example of an annotation file - The annotation file contains a row for each of the features of the count matrix. Furthermore, the file contains at least one column called gene names which contains a more human readable for of the feature identifiers of the rows. In the shown example the feature ids are ENSEMBL ids while the column gene names contains HGNC gene names.

Exploring the data with pcaExplorer

Before we start with the exploration of the data, the necessary packages and dependencies need to be installed and loaded. Support Protocol 1 describes how to install and load the packages.

1. Prepare the input data. Launch the Shiny application with the command pcaExplorer(countmatrix, metadata, annotation) where countmatrix, metadata and annotation have to be substituted by the file paths of the respective input files. To launch the application, enter the command into the console of RStudio and press the Enter-Button. This should launch a second window with the pcaExplorer application. In this application you should see the Data Upload panel as shown in Fig. 4.

Figure 4 Data Upload panel - The figure shows the Data Upload panel which is the first panel a user sees upon launching pcaExplorer. The panel provides previes on the input data as well as buttons to interact with the application.

2. Click the “Generate the dds and dst object” button to generate the dds and dst object needed for the exploration of the data (Fig 4). Scroll down on the Data Upload panel. After the generation of the dds and dst object you should find the ‘Select one of the following transformations for your data:’ option with three blue colored buttons underneath. Each button describes a different transformation of the data. The first button on the far left ‘Compute variance stabilized transformed data from the dds object’ computes a variance stabilized transformed version on the data upon clicking the button. The middle button computes a regularized logarithm transformed version of the data, while the button on the far right computes log2 data. The choice of transformation of the data in this step should be dependent on the input data. If you follow this protocol using the provided sample data, click the ‘Compute variance stabilized transformed data from the dds object’ button on the far left.

3. At the bottom of the Data Upload panel, a preview of the input data is provided. Here you’ll find four green colored buttons which provide a preview on the respective input data upon clicking.

4. Navigate to the Counts Table panel through clicking on the panel name in the panel list at the beginning of each panel (Fig. 5). In this panel, the count information of the count matrix is shown in a table. A drop-down menu at the beginning of the panel provides the possibility to change the data scale in the table. Different options can be chosen through clicking (e.g. raw counts, normalized counts, regularized logarithm transformed counts, etc.). Users can download the counts table through clicking on the green download button below the table (Fig. 5).

Figure 5 Counts Table panel - The figure shows the Counts Table panel. This panel provides an overview of the input counts matrix.

5. Scroll down until you see the ‘Sample to sample scatter plots’ heading (Fig. 5). Choose ‘pearson’ as correlation method from the ‘Correlation method palette’. Ensure that both options ‘Use log2 values for plot axes and values’ and ‘Use a subset of max 1000 genes (quicker to plot)’ are selected. An option is selected, if the small box in front of the option is ticked (Fig. 5). Click on the ‘Run’ button to generate the scatter plots.

6. TODO: Something about the inspection of the plot and some general remarks to the type of plots

Figure 6

Figure 7 Sample to Sample similarity heatmap

7. Navigate to the Data Overview panel through clicking on the panel name in the panel list at the beginning of each panel (Fig. 8). The panel shows the input metadata as table in the upper half of the panel. The number of entries shown in the table can be managed with the “Show X entries” drop down menu. Furthermore, in the right upper corner of the table, users can find a Search field, which can be used to search for specific terms in the metadata table (Fig. 8). Below the metadata table, a Sample to Sample distance heatmap can be found. This heatmap reflects the distances between the individual samples. The “Select the distance method to use” option enables users to change the distance method used for the heatmap. Furthermore, users have the option to download the heatmap via the “Download Plot” button in the lower right corner below the heatmap. In the field “Save as…” users can specify the name of the file to save the heatmap (Fig 8).

Figure 8

8. Scroll down in the Data Overview panel. Below the heatmap, the panel provides further information about the input data (Fig. 9 & 10).

Figure 9

Figure 10

9. Navigate to the Samples View panel through clicking on the panel name in the panel list at the beginning of each panel (Fig. 11). When directed to the panels, users see the PCA of the individual samples of the iput data on the left side with the corresponding scree plot shown on the right side. Initially the samples shown in the PCA are not colored by any group hence it is hard to identify the characteristics of the samples along which the PCA groups the samples. In the presented data, users should color the samples by condition. To color the samples by condition, click on the “Group/color by” filed on the grey side bar at the far left of the screen. Scroll down in the drop-down menu which opens upon clicking until you find the “condition” option. Click this option. It should now be displayed in the before empty field (Fig. 12). Furthermore, the PCA plot changed displaying the samples now in 4 colors compared to one before (Fig. 12). Users can also download the PCA plor via the “Download plot” button in the lower right corner of the plot. As seen before, users can specify the name of the file they want to save the plot. This is also possible for the Screeplot on the right side of the panel.

some notes about how to delete option, identifiy the right optio for you data and how to use the scree plot

Figure 11 The Samples View panel - This panel shows a PCA of the individual samples of the input data. In the upper part of the panel, the PCA on the samples and the corresponding scree plot are shown. Initially there is no grouping shown in the PCA.

Figure 12 PCA colored by condition - The PCA plot of the samples is shown colored by condition. This coloring is achieved by selecting the option “condition” in the “Group/color by” selection tab at the far left of the screen. The tab indicates the selected option by displaying the name of the option in the field. Users can remove options by clicking into the option field right behind the option to be deleted and hitting the delete key on the keyboard.

10. The Sample View panel provides the possibility to zoom in on the PCA. For this, hover your mouse over the PCA plot until your mouse pointer changes to a little plus sign. Press the left button of the mouse and move the mouse to draw a little grey rectagle (Fig. 13). Move the mouse to the upper left corner of the PCA plot and select all samples belonging to the naive condition (colored in blue in Fig. 12) as explained before. After selecting the samples, scroll down in the panel until you see a zoomed in version of the PCA plot containing mainly the selected sampels. This should somewhat look like the plot shown in Fig. 13.

Figure 13 Zoomed in PCA plot - The figure shows the zooming mechanism on the PCA plot of the Samples View panel. The grey rectangle in the upper PCA plot indicates the portion of the PCA plot selected for zooming. This selected portion of the plot is shown in the lower PCA plot in more detail.

14. The zoomed in PCA plot can be downloaded via the “Download plot” button in the lower right corner below the plot. As aforementioned the name of the file to save the plot can also be specified.

15. Something about the plot on the right sied of the zoomed in PCA

16. Scroll down in the Sample View panel until you see the “Outlier identification” option (Fig. 14). The “Select which sample(s) to remove - suspected outliers” options provides the possibility to select individual samples, which are suspected to be outliers, and remove them from the PCA. For demonstration purposes select all samples from the “naive” condition and remove them from the PCA (the sample ids end in “102”, “111”, “182”, “262”, “284” and “368”). To remove samples from the plot, click on the field below the “Select which sample(s) to remove - suspected outliers” option. This opens a drop-won menu with the sample ids of all samples listed. Select the above mentioned sample ids until the PCA plot looks like Fig. 15.

Something about the plot at the bottom of the panel and overall outlier identification

Figure 14 Outlier identification - The Samples View panel provides the possibility to detect outliers.

Figure 15 PCA plot with outliers removed - THe figures shows the PCA plot with all samples of the “naive” condition removed. With this type of sample selection, outlier samples in the data can be detected and removed from the PCA.

17. Navigate to the “Intructions” panel through clicking on the panel name in the panel list at the beginning of each panel (Fig. 16). Open the vignettes of pcaExplorer by clicking on the two buttons “Open the User Guide (main vignette)” and “Open the ‘UP and Running’ vignette”. This will open the two vignettes of pcaExplorer in your selected default browser. The vignettes describe the individual panels of pcaExplorer in detail and provide walkthroughs on how to explore input data with pcaExplorer. Users are recommended to read the vignettes to fully graps the different possibilities provided with pcaExplorer.

Figure 16 Instructions panel

Session information

sessionInfo()

## R version 4.1.1 (2021-08-10)
## Platform: x86_64-w64-mingw32/x64 (64-bit)
## Running under: Windows 10 x64 (build 19042)
## 
## Matrix products: default
## 
## locale:
## [1] LC_COLLATE=German_Germany.1252  LC_CTYPE=German_Germany.1252    LC_MONETARY=German_Germany.1252
## [4] LC_NUMERIC=C                    LC_TIME=German_Germany.1252    
## 
## attached base packages:
## [1] parallel  stats4    stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
##  [1] GeneTonic_1.4.1             ideal_1.16.0                pcaExplorer_2.18.0         
##  [4] org.Mm.eg.db_3.13.0         topGO_2.44.0                SparseM_1.81               
##  [7] GO.db_3.13.0                AnnotationDbi_1.54.1        graph_1.70.0               
## [10] DESeq2_1.32.0               SummarizedExperiment_1.22.0 Biobase_2.52.0             
## [13] MatrixGenerics_1.4.3        matrixStats_0.60.1          GenomicRanges_1.44.0       
## [16] GenomeInfoDb_1.28.2         IRanges_2.26.0              S4Vectors_0.30.0           
## [19] BiocGenerics_0.38.0         knitr_1.33                 
## 
## loaded via a namespace (and not attached):
##   [1] utf8_1.2.2               shinydashboard_0.7.1     tidyselect_1.1.1        
##   [4] heatmaply_1.2.1          RSQLite_2.2.8            htmlwidgets_1.5.3       
##   [7] grid_4.1.1               TSP_1.1-10               BiocParallel_1.26.2     
##  [10] IHW_1.20.0               munsell_0.5.0            codetools_0.2-18        
##  [13] DT_0.19                  rentrez_1.2.3            miniUI_0.1.1.1          
##  [16] withr_2.4.2              colorspace_2.0-2         Category_2.58.0         
##  [19] filelock_1.0.2           shinyWidgets_0.6.0       NMF_0.23.0              
##  [22] slam_0.1-48              GenomeInfoDbData_1.2.6   lpsymphony_1.20.0       
##  [25] polyclip_1.10-0          farver_2.1.0             bit64_4.0.5             
##  [28] pheatmap_1.0.12          vctrs_0.3.8              generics_0.1.0          
##  [31] xfun_0.25                BiocFileCache_2.0.0      R6_2.5.1                
##  [34] doParallel_1.0.16        clue_0.3-59              seriation_1.3.0         
##  [37] locfit_1.5-9.4           bitops_1.0-7             cachem_1.0.6            
##  [40] shinyAce_0.4.1           DelayedArray_0.18.0      assertthat_0.2.1        
##  [43] shinycssloaders_1.0.0    promises_1.2.0.1         BiocIO_1.2.0            
##  [46] scales_1.1.1             gtable_0.3.0             Cairo_1.5-12.2          
##  [49] rlang_0.4.11             genefilter_1.74.0        GlobalOptions_0.1.2     
##  [52] splines_4.1.1            rtracklayer_1.52.1       lazyeval_0.2.2          
##  [55] bs4Dash_2.0.2            shinyBS_0.61             BiocManager_1.30.16     
##  [58] yaml_2.2.1               reshape2_1.4.4           GenomicFeatures_1.44.2  
##  [61] threejs_0.3.3            crosstalk_1.1.1          httpuv_1.6.2            
##  [64] RBGL_1.68.0              backbone_1.5.0           tools_4.1.1             
##  [67] bookdown_0.24            gridBase_0.4-7           ggplot2_3.3.5           
##  [70] ellipsis_0.3.2           gplots_3.1.1             jquerylib_0.1.4         
##  [73] RColorBrewer_1.1-2       dynamicTreeCut_1.63-1    Rcpp_1.0.7              
##  [76] plyr_1.8.6               visNetwork_2.0.9         base64enc_0.1-3         
##  [79] progress_1.2.2           zlibbioc_1.38.0          purrr_0.3.4             
##  [82] RCurl_1.98-1.4           BiasedUrn_1.07           prettyunits_1.1.1       
##  [85] GetoptLong_1.0.5         viridis_0.6.1            ggrepel_0.9.1           
##  [88] cluster_2.1.2            magrittr_2.0.1           data.table_1.14.0       
##  [91] circlize_0.4.13          colourpicker_1.1.0       goseq_1.44.0            
##  [94] hms_1.1.0                mime_0.11                evaluate_0.14           
##  [97] xtable_1.8-4             XML_3.99-0.7             shape_1.4.6             
## [100] gridExtra_2.3            compiler_4.1.1           biomaRt_2.48.3          
## [103] tibble_3.1.4             KernSmooth_2.23-20       crayon_1.4.1            
## [106] htmltools_0.5.2          GOstats_2.58.0           mgcv_1.8-36             
## [109] later_1.3.0              tidyr_1.1.3              geneplotter_1.70.0      
## [112] expm_0.999-6             DBI_1.1.1                tweenr_1.0.2            
## [115] geneLenDataBase_1.28.0   ComplexHeatmap_2.8.0     dbplyr_2.1.1            
## [118] MASS_7.3-54              rappdirs_0.3.3           BiocStyle_2.20.2        
## [121] Matrix_1.3-4             igraph_1.2.6             pkgconfig_2.0.3         
## [124] GenomicAlignments_1.28.0 registry_0.5-1           plotly_4.9.4.1          
## [127] xml2_1.3.2               foreach_1.5.1            annotate_1.70.0         
## [130] bslib_0.3.0              rngtools_1.5             pkgmaker_0.32.2         
## [133] webshot_0.5.2            XVector_0.32.0           AnnotationForge_1.34.0  
## [136] stringr_1.4.0            digest_0.6.27            Biostrings_2.60.2       
## [139] rmarkdown_2.10           rintrojs_0.3.0           dendextend_1.15.1       
## [142] GSEABase_1.54.0          restfulr_0.0.13          curl_4.3.2              
## [145] shiny_1.6.0              Rsamtools_2.8.0          gtools_3.9.2            
## [148] rjson_0.2.20             lifecycle_1.0.0          nlme_3.1-152            
## [151] jsonlite_1.7.2           viridisLite_0.4.0        limma_3.48.3            
## [154] fansi_0.5.0              pillar_1.6.2             lattice_0.20-44         
## [157] KEGGREST_1.32.0          fastmap_1.1.0            httr_1.4.2              
## [160] survival_3.2-11          glue_1.4.2               fdrtool_1.2.16          
## [163] UpSetR_1.4.0             png_0.1-7                iterators_1.0.13        
## [166] bit_4.0.4                Rgraphviz_2.36.0         ggforce_0.3.3           
## [169] stringi_1.7.4            sass_0.4.0               blob_1.2.2              
## [172] caTools_1.18.2           memoise_2.0.0            dplyr_1.0.7